<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Quantities and Units</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Quaternions.xhtml" title="Quaternions"/>
    <link rel="next" href="Logical-Number-Operations.xhtml" title="Logical Number Operations"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Quantities and Units" epub:type="subchapter" id="Quantities">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Quantities and Units</h2>
          </div>
        </div>
      </div>
      <p>As a super-class of numbers, Kawa also provides quantities.
A <em class="firstterm">quantity</em> is a product of a <em class="firstterm">unit</em> and a pure number.
The number part can be an arbitrary complex number.
The unit is a product of integer powers of base units,
such as meter or second.
</p>
      <p>Quantity literals have the following syntax:
</p>
      <div class="literallayout">
        <p><a id="idm139667876256832" class="indexterm"/><span id="meta-quantity"/><em class="replaceable"><code>quantity</code></em> <code class="literal">::=</code> <a class="link" href="Lexical-syntax.xhtml#meta-optional-sign"><em class="replaceable"><code>optional-sign</code></em></a> <a class="link" href="Lexical-syntax.xhtml#meta-decimal"><em class="replaceable"><code>decimal</code></em></a> <a class="link" href="Quantities.xhtml#meta-unit-term"><em class="replaceable"><code>unit-term</code></em></a> [<code class="literal"><span class="bold"><strong>*</strong></span></code> <a class="link" href="Quantities.xhtml#meta-unit-term"><em class="replaceable"><code>unit-term</code></em></a>]... [<code class="literal"><span class="bold"><strong>/</strong></span></code> <a class="link" href="Quantities.xhtml#meta-unit-term"><em class="replaceable"><code>unit-term</code></em></a>]<br/>
<a id="idm139667876249168" class="indexterm"/><span id="meta-unit-term"/><em class="replaceable"><code>unit-term</code></em> <code class="literal">::=</code> <a class="link" href="Quantities.xhtml#meta-unit-name"><em class="replaceable"><code>unit-name</code></em></a> [<code class="literal"><span class="bold"><strong>^</strong></span></code> <a class="link" href="Lexical-syntax.xhtml#meta-digit"><em class="replaceable"><code>digit</code></em></a>+]<br/>
<a id="idm139667876244768" class="indexterm"/><span id="meta-unit-name"/><em class="replaceable"><code>unit-name</code></em> <code class="literal">::=</code> <a class="link" href="Lexical-syntax.xhtml#meta-letter"><em class="replaceable"><code>letter</code></em></a>+<br/>
</p>
      </div>
      <p>Some examples are <code class="literal">10pt</code> (10 points), <code class="literal">5s</code> (5 seconds),
and <code class="literal">4cm^2</code> (4 square centimeters).
</p>
      <p>Note the <em class="replaceable"><code>quantity</code></em> syntax is not recognized by the reader.
Instead these are read as symbols.
Assuming there is no lexical binding the for the symbol, it will be
rewritten at compile-time into an expression.  For example <code class="literal">4cm^2</code>
is transformed into:
</p>
      <pre class="screen">(* 4.0 (expt unit:cm 2))
</pre>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667876238288" class="indexterm"/> <code class="function">quantity?</code> <em class="replaceable"><code>object</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>True iff <em class="replaceable"><code>object</code></em> is a quantity.  Note that all numbers are
quantities, but not the other way round.
Currently, there are no quantities that are not numbers.
To distinguish a plain unit-less number from a quantity,
you can use <code class="literal">complex?</code>.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667876232832" class="indexterm"/> <code class="function">quantity-&gt;number</code> <em class="replaceable"><code>q</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns the pure number part of the quantity <em class="replaceable"><code>q</code></em>, relative to
primitive (base) units.
If <em class="replaceable"><code>q</code></em> is a number, returns <em class="replaceable"><code>q</code></em>.
If <em class="replaceable"><code>q</code></em> is a unit, yields the magitude of <em class="replaceable"><code>q</code></em> relative to base units.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667876227312" class="indexterm"/> <code class="function">quantity-&gt;unit</code> <em class="replaceable"><code>q</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns the unit of the quantity <em class="replaceable"><code>q</code></em>.
If <em class="replaceable"><code>q</code></em> is a number, returns the empty unit.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667876223104" class="indexterm"/> <code class="function">make-quantity</code> <em class="replaceable"><code>x</code></em> <em class="replaceable"><code>unit</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns the product of <em class="replaceable"><code>x</code></em> (a pure number) and <em class="replaceable"><code>unit</code></em>.
You can specify a string instead of <em class="replaceable"><code>unit</code></em>, such as <code class="literal">"cm"</code>
or <code class="literal">"s"</code> (seconds).
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667876217120" class="indexterm"/> <code class="function">define-base-unit</code> <em class="replaceable"><code>unit-name</code></em> <em class="replaceable"><code>dimension</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Define <em class="replaceable"><code>unit-name</code></em> as a base (primitive) unit,
which is used to measure along the specified <em class="replaceable"><code>dimension</code></em>.
</p>
          <pre class="screen">(define-base-unit dollar "Money")
</pre>
        </blockquote>
      </div>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667876212080" class="indexterm"/> <code class="function">define-unit</code> <em class="replaceable"><code>unit-name</code></em> <em class="replaceable"><code>expression</code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Define <em class="replaceable"><code>unit-name</code></em> as a unit (that can be used in literals)
equal to the quantity <em class="replaceable"><code>expression</code></em>.
</p>
          <pre class="screen">(define-unit cent 0.01dollar)
</pre>
          <p>The <em class="replaceable"><code>unit-name</code></em> is declared in the <code class="literal">unit</code> namespace,
so the above is equivalent to:
</p>
          <pre class="screen">(define-constant unit:cent (* 0.01 unit:dollar))
</pre>
        </blockquote>
      </div>
      <h3 id="idm139667876205744">Angles</h3>
      <p>The following angle units are dimensionless, with no base unit.
</p>
      <p>Some procedures treat a unit-less real number as if it were in radians
(which mathematicians prefer);
some procedures (such as <code class="literal">rotate</code>) treat a unit-less real number
as if it were in degrees
(which is common in Web and other standards).
</p>
      <p class="synopsis" kind="Unit"><span class="kind">Unit</span><span class="ignore">: </span><a id="idm139667876203408" class="indexterm"/> <code class="function">rad</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>A unit for angles specified in radians.
A full circle is 2*pi radians.
Note that <code class="literal">(= 1.5 1.5rad)</code> is true,
while <code class="literal">(eqv? 1.5 1.5rad)</code> is false.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Unit"><span class="kind">Unit</span><span class="ignore">: </span><a id="idm139667876199504" class="indexterm"/> <code class="function">deg</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>A unit for angles specified in degrees.
A full circle is 360 degrees.
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Unit"><span class="kind">Unit</span><span class="ignore">: </span><a id="idm139667876196512" class="indexterm"/> <code class="function">grad</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>A unit for angles specified in gradians.
A full circle is 400 gradians.
</p>
        </blockquote>
      </div>
    </section>
    <footer>
      <div class="navfooter">
        <p>
          Up: <a accesskey="u" href="Numbers.xhtml">Quantities and Numbers</a></p>
        <p>
        Previous: <a accesskey="p" href="Quaternions.xhtml">Quaternions</a></p>
        <p>
        Next: <a accesskey="n" href="Logical-Number-Operations.xhtml">Logical Number Operations</a></p>
      </div>
    </footer>
  </body>
</html>
